27장 Hooks로 자동 실행 걸기 (입문판)

원서: 클로드 코드 완벽 가이드 (코드팩토리 최지호)

이 장에서 딱 5가지만 1. Hooks(훅)는 "정해진 순간에 자동으로 내 명령을 실행해 주는 장치"다. 2. 훅은 JSON 파일에 적어두면 된다. 어디 적느냐에 따라 적용 범위가 달라진다. 3. 훅 JSON은 "이벤트 → matcher → hooks → command" 순서로 한 겹씩 들어간다. 4. 훅을 걸 수 있는 순간(이벤트)은 7가지가 있다. 5. 훅이 실행될 때 클로드 코드가 stdin으로 정보를 넘겨준다. 그 정보로 무엇을 할지 정할 수 있다.

안내: 이 장에 나오는 훅 이벤트 이름이나 설정 방식은 원서/노트 기준 예시이며, 최신 값은 클로드 코드 공식 문서에서 확인하세요.

학습 목표

이 장을 끝내면 여러분은 - 훅(Hook)이 무엇이고 왜 쓰는지 설명한다. - 훅 설정 파일 3곳의 적용 범위를 구분한다. - 훅 JSON 구조를 한 겹씩 설명한다. - 7가지 훅 이벤트를 구분한다. - 간단한 훅을 직접 따라 한다.

27-1 훅이 뭐예요?

이런 적 있죠?

여러분이 클로드 코드로 코드를 고치고 있어요. 파일 하나 고치고 나면 "린트 검사"라는 걸 돌려야 코드가 깔끔한지 알 수 있어요.

린트(lint): 코드에 오타나 규칙 위반이 없는지 자동으로 잡아주는 검사. 일상으로 치면 "맞춤법 검사기" 같은 거예요.

그런데 파일을 고칠 때마다 손으로 린트 명령어를 쳐야 해요. 한두 번은 괜찮은데, 열 번 스무 번 하다 보면 까먹어요. 까먹으면? 엉성한 코드가 그대로 남죠.

"파일 고칠 때마다 자동으로 린트가 돌면 좋을 텐데..."

바로 그걸 해주는 게 훅(Hook)이에요.

그게 바로 '훅'

훅(Hook)이란, 정해진 순간에 내가 미리 적어둔 명령을 자동으로 실행해 주는 장치예요.

훅(Hook): 프로그램이 흘러가는 도중 "이 순간"에 내 명령을 걸어두는 장치. 일상으로 치면 빨래 건조대에 옷을 거는 '갈고리'처럼, 실행 흐름의 한 지점에 내 작업을 '걸어두는' 거예요.

"파일이 고쳐지면" 같은 순간을 정해두고, 거기에 "린트를 돌려라" 같은 명령을 걸어두는 거죠. 그러면 그 순간이 올 때마다 클로드 코드가 알아서 명령을 실행해 줘요.

비유로 먼저

훅은 요리 과정에 끼워 넣는 '중간 점검' 같아요.

요리사(클로드 코드)가 요리를 한다고 해봐요. - 재료를 손질하기 전 → "재료 상태 점검!" - 재료를 손질한 후 → "잘 손질됐나 확인!" - 손님에게 주문을 받을 때 → "주문 내용 검증!" - 요리를 완성했을 때 → "최종 맛 점검!"

각 단계마다 내가 원하는 점검을 끼워 넣을 수 있는 거예요.

잘못된 예 vs 올바른 예

잘못된 방식 (훅 없이):

파일 수정 → 내가 직접 린트 실행 → 또 수정 → 또 직접 린트...
→ 한 번 까먹으면 엉성한 코드가 남음

올바른 방식 (훅 설정):

파일 수정 → (훅이 자동으로) 린트 실행
→ 까먹을 일 없이 매번 자동 점검

미니 시나리오: 팀 프로젝트에서 "파일 고치면 무조건 포맷 정리"를 규칙으로 정하고 싶다. 이럴 때 훅을 걸어두면, 팀원 누가 작업하든 자동으로 정리돼요.

한 걸음 더 ▸ 훅의 두 가지 이점

• 확장성: 클로드 코드의 기본 동작에 내가 만든 명령을 덧붙일 수 있어요.
• 맞춤화: 프로젝트마다 다른 자동화(린트, 테스트, 알림)를 설정해 작업 흐름을 세밀하게 다룰 수 있어요.

27-2 훅은 어디에 적어요?

이런 적 있죠?

훅을 만들기로 했어요. 그런데 "이걸 어디에 적지?"가 막혀요. - 내 모든 프로젝트에 적용하고 싶으면? - 이 프로젝트만 적용하고 싶으면? - 나만 몰래 쓰고 싶으면?

적는 위치에 따라 적용 범위가 달라져요. 그래서 위치를 알아야 해요.

그게 바로 '설정 파일 3곳'

훅은 JSON 파일에 적어요. 적을 수 있는 곳이 세 군데예요.

JSON 파일: 정보를 { }와 [ ]로 깔끔하게 정리해 적는 글쓰기 형식. 0장 용어집 참고. 일상으로 치면 "칸이 정해진 신청서"예요. 정해진 칸에 정해진 모양으로 적는 거죠.

비유로 먼저

설정 파일 위치는 규칙을 적용하는 범위라고 보면 돼요.

• 학교 전체 규칙(~/.claude/settings.json) → 모든 반에 적용. 즉 내 모든 프로젝트에 적용.
• 우리 반 규칙(.claude/settings.json) → 이 반에만 적용. 즉 이 프로젝트에만 적용.
• 나만의 규칙(.claude/settings.local.json) → 나만 적용. 다른 사람과 공유 안 됨.

범위가 좁을수록 더 개인적인 설정이에요.

여기서 ~(물결표)는 "내 홈 폴더"를 뜻해요. 일상으로 치면 "내 방"이에요.

왜 .local.json이 따로 있을까?

.claude/settings.local.json은 Git에 올라가지 않아요.

Git: 코드 변경 내역을 저장하고 팀과 공유하는 도구. 0장 용어집 참고. 일상으로 치면 "공유 사물함"이에요.

그래서 팀원과 공유하고 싶지 않은, 나만 쓰는 실험용 훅을 적기에 딱이에요.

잘못된 예 vs 올바른 예

상황: 팀 공통 훅과 내 개인 훅을 섞어 적었다.

잘못된 예:

팀 훅 + 개인 실험 훅을 모두 .claude/settings.json에 적음
→ 커밋하면 내 실험용 훅까지 팀에 퍼짐

올바른 예:

팀 공통 훅 → .claude/settings.json (커밋, 공유)
개인 실험 훅 → .claude/settings.local.json (공유 안 됨)

미니 시나리오: 나만 슬랙 알림을 받고 싶다. → .claude/settings.local.json에 적으면 팀원은 영향받지 않아요.

27-3 훅 JSON은 어떻게 생겼어요?

이런 적 있죠?

훅을 적기로 했어요. 그런데 JSON을 열어보니 { } 안에 또 [ ]가 있고, 그 안에 또 { }가 있어요. "이게 무슨 미로야..." 싶죠.

사실 규칙만 알면 쉬워요. 한 겹씩 까보면 돼요.

그게 바로 '계층 구조'

훅 JSON은 양파처럼 한 겹씩 들어가요. 바깥부터 안으로 "어느 순간 → 어떤 도구 → 무슨 명령" 순서예요.

비유로 먼저

훅 JSON은 택배 분류 안내문 같아요. - 바깥 봉투에 "도착 즉시 처리"라고 적혀 있고 (이벤트) - 그 안에 "빨간 상자만" 라벨이 있고 (matcher) - 가장 안쪽에 "이 상자는 냉장 보관" 지시가 있어요 (command).

실제 모습 (터미널 예)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '쉘 명령 실행 전입니다!'"
          }
        ]
      }
    ]
  }
}

한 겹씩 풀어 읽으면 이래요.

bash 명령어: 터미널에 직접 치는 명령. 0장 용어집 참고. 예: echo, npm run lint.

잘못된 예 vs 올바른 예

상황: timeout을 꼭 적어야 하나 헷갈린다.

잘못된 이해:

"timeout은 필수다. 안 적으면 에러난다."

올바른 이해:

"timeout은 선택이다. 안 적으면 기본값으로 동작한다.
 type과 command만 필수다."

미니 시나리오: 오래 걸리는 검사를 걸었는데 30초 넘으면 멈추게 하고 싶다. → "timeout": 30을 추가하면 돼요.

27-4 matcher로 도구 골라내기

이런 적 있죠?

"파일을 수정할 때만" 훅을 돌리고 싶어요. 그런데 클로드 코드는 파일 읽기, 웹 검색, 명령 실행 등 여러 도구를 써요. 이 모든 순간에 훅이 다 돌면? 쓸데없이 자꾸 검사가 돌아 번거로워요.

"내가 원하는 도구일 때만 골라서 돌릴 순 없을까?"

그걸 해주는 게 matcher예요.

그게 바로 'matcher'

matcher는 "어떤 도구에만 훅을 돌릴지" 골라내는 패턴이에요.

matcher: "이 도구 이름과 맞으면 훅 실행"을 정하는 패턴. 일상으로 치면 "이 라벨이 붙은 것만 골라내는 분류기"예요.

중요한 점: matcher는 도구를 쓰는 두 이벤트(PreToolUse, PostToolUse)에서만 써요. 나머지 이벤트는 matcher가 필요 없어요. (도구와 상관없는 순간이니까요.)

비유로 먼저

matcher는 택배 분류기 같아요.

모든 택배(도구 호출)가 컨베이어 벨트에 올라오면, 분류기(matcher)가 라벨을 봐요. - "Bash" 라벨 → Bash 전용 훅 실행 - "Edit|Write" 라벨 → 파일 수정 훅 실행 - 그 외 → 그냥 통과 (훅 실행 안 함)

실제 패턴 예 (터미널 예)

"Bash"               → Bash 도구만 매칭
"Edit|MultiEdit|Write" → 파일 수정 관련 3개 모두 매칭
"Read"               → 파일 읽기 도구만 매칭
"WebFetch|WebSearch" → 웹 관련 도구만 매칭

여기서 |(세로 막대)는 "또는"이라는 뜻이에요. 이렇게 여러 도구를 한 번에 묶는 걸 정규식이라고 해요.

정규식(Regex): 글자 패턴을 표현하는 작은 규칙. 0장 용어집 참고. 일상으로 치면 "검색할 때 쓰는 와일드카드(*)" 같은 거예요. 여기서는 |(또는)만 알면 충분해요.

matcher에 쓸 수 있는 주요 도구 이름

잘못된 예 vs 올바른 예

잘못된 이해:

"matcher는 모든 훅 이벤트에 꼭 적어야 한다."

올바른 이해:

"matcher는 PreToolUse, PostToolUse에서만 쓴다.
 나머지(UserPromptSubmit, Notification, Stop,
 SubagentStop, PreCompact)는 matcher를 생략한다."

미니 시나리오: 파일을 새로 만들 때만 알림을 보내고 싶다. → matcher: "Write"로 Write 도구만 골라내면 돼요.

27-5 훅을 걸 수 있는 7가지 순간

이런 적 있죠?

훅을 걸고 싶은데 "정확히 어느 순간에 걸 수 있지?"가 궁금해요. 파일 고치기 전? 다 끝난 후? 알림이 올 때?

클로드 코드는 훅을 걸 수 있는 순간을 7가지 정해뒀어요. 이 7개만 알면 "내가 원하는 순간"을 고를 수 있어요.

그게 바로 '7가지 훅 이벤트'

이벤트(event): 훅을 걸 수 있는 "순간"의 이름. 일상으로 치면 알람을 맞출 수 있는 정해진 시각들이에요.

비유로 먼저

7가지 훅은 축구 경기의 7가지 체크포인트 같아요.

• 선수가 공을 차기 직전 → "자세 점검!" (PreToolUse)
• 선수가 공을 찬 직후 → "결과 확인!" (PostToolUse)
• 심판이 호루라기를 불 때 → "상황 전달!" (Notification)
• 감독이 전술을 지시할 때 → "전술 검증!" (UserPromptSubmit)
• 주심이 경기를 끝낼 때 → "최종 정리!" (Stop)
• 부심이 판정을 마칠 때 → "부심 결과 확인!" (SubagentStop)
• 하프타임에 정리할 때 → "정리 전 점검!" (PreCompact)

7가지 한눈에 보기

프롬프트(prompt): 내가 클로드에게 보내는 요청 문장. 0장 용어집 참고. 서브에이전트(subagent): 메인 클로드가 시킨 작은 일을 대신 처리하는 보조 일꾼. 일상으로 치면 "부주방장"이에요. 컨텍스트 압축(compact): 대화가 너무 길어지면 요점만 추려 짧게 줄이는 것. 일상으로 치면 "긴 회의록을 요약하는" 거예요.

알아두면 좋은 두 가지 포인트

1) Notification은 언제 오나? 사용자 승인을 기다릴 때, 또는 60초 동안 아무 입력이 없을 때(유휴) 알림이 와요.

2) Stop은 항상 실행될까? 아니에요. 응답을 정상적으로 마쳤을 때만 실행돼요. 내가 중간에 끊으면(인터럽트) Stop 훅은 실행되지 않아요.

인터럽트(interrupt): 작업 도중 내가 강제로 멈추는 것. 일상으로 치면 "말하는 중간에 끊는" 거예요.

PreCompact만 좀 달라요

PreCompact는 도구 matcher 대신 trigger 값으로 상황을 구분해요.

trigger: "manual" → 내가 /compact 명령으로 직접 압축할 때
trigger: "auto"   → 컨텍스트가 가득 차서 자동으로 압축될 때

수동(manual)일 때는 custom_instructions에 내 지시를 넘길 수 있어요. 자동(auto)일 때는 이 칸이 비어 있어요.

/compact: 대화를 직접 요약·압축하라고 시키는 클로드 코드 명령. 일상으로 치면 "회의록 지금 요약해줘" 버튼이에요.

실전 시나리오별 추천 훅

시나리오 1: 파일 수정 시 자동 포맷팅
→ PostToolUse + matcher: "Edit|MultiEdit|Write"
→ command: "prettier --write $FILE_PATH"

시나리오 2: 프롬프트에 프로젝트 규칙 자동 주입
→ UserPromptSubmit (matcher 불필요)
→ command: "cat $CLAUDE_PROJECT_DIR/.rules"

시나리오 3: 위험한 명령 실행 전 경고
→ PreToolUse + matcher: "Bash"
→ command: "echo '쉘 명령 실행 전 주의!'"

시나리오 4: 응답 완료 후 슬랙 알림
→ Stop (matcher 불필요)
→ command: "curl -X POST slack-webhook-url"

$CLAUDE_PROJECT_DIR: 훅 명령 안에서 쓸 수 있는 환경 변수로, 지금 프로젝트의 루트 폴더 경로를 담고 있어요. 일상으로 치면 "현재 작업 중인 방 주소"예요.

잘못된 예 vs 올바른 예

잘못된 이해:

"7개 이벤트 전부 matcher가 필요하다."

올바른 이해:

"matcher가 필요한 건 PreToolUse, PostToolUse 둘뿐.
 나머지 5개는 matcher 없이 동작한다."

27-6 훅에게 전달되는 정보 (stdin)

이런 적 있죠?

훅을 만들긴 했는데, "지금 어떤 도구가 실행됐는지" "결과가 성공인지"를 알아야 제대로 된 후처리를 할 수 있어요. 이런 정보를 매번 내가 손으로 알아내야 한다면 너무 번거롭겠죠.

다행히 클로드 코드가 훅을 실행할 때, 필요한 정보를 알아서 넘겨줘요. 그 통로가 바로 stdin이에요.

그게 바로 'stdin으로 받는 정보'

stdin(표준 입력): 프로그램이 정보를 받아들이는 기본 통로. 0장 용어집 참고. 일상으로 치면 "우편함"이에요. 클로드 코드가 이 우편함에 정보를 넣어주면, 훅이 꺼내 읽어요.

훅이 실행되면, 클로드 코드가 stdin으로 JSON 정보를 넣어줘요. 이 정보는 공통 정보와 이벤트별 고유 정보로 나뉘어요.

비유로 먼저

stdin JSON은 훅에게 건네는 작업 지시서 같아요.

모든 지시서에 공통으로 적히는 정보가 있어요.

그리고 이벤트마다 추가로 붙는 고유 정보가 달라요.

이벤트별 고유 정보

PreToolUse:
  tool_name   → 호출될 도구 이름 (예: "Write", "Bash")
  tool_input  → 도구에 넘어갈 입력값
                (Write라면 file_path, content 등)

PostToolUse:
  tool_name     → 실행된 도구 이름
  tool_input    → 도구에 넘어갔던 입력값
  tool_response → 도구 실행 결과 (filePath, success 등)

Notification:
  message → 알림 메시지 내용

UserPromptSubmit:
  prompt → 내가 입력한 프롬프트 내용

Stop / SubagentStop:
  stop_hook_active → Stop 훅이 진행 중인지 여부

PreCompact:
  trigger             → "manual" 또는 "auto"
  custom_instructions → 수동 압축 시 내 지시 (자동이면 비어 있음)

핵심 차이: PostToolUse에만 있는 tool_response

PreToolUse는 도구를 쓰기 전이라 아직 결과가 없어요. 그래서 tool_response가 없어요. PostToolUse는 도구를 쓴 후라 결과가 있어요. 그래서 tool_response가 붙어요.

실제 훅 스크립트 예 (터미널 예)

PostToolUse에서 결과를 기록 파일에 남기는 예예요.

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo $INPUT | jq -r '.tool_name')
SUCCESS=$(echo $INPUT | jq -r '.tool_response.success')
echo "[$TOOL] 실행 결과: $SUCCESS" >> hook_log.txt

읽는 법: - $(cat) → 우편함(stdin)에서 정보를 꺼내요. - jq -r '.tool_name' → JSON에서 도구 이름만 뽑아요. - 마지막 줄 → "도구 이름과 성공 여부"를 기록 파일에 한 줄 남겨요.

jq: JSON에서 원하는 값만 쏙 뽑아내는 도구. 일상으로 치면 "신청서에서 이름 칸만 골라 읽기"예요.

잘못된 예 vs 올바른 예

잘못된 이해:

"모든 훅 이벤트가 똑같은 JSON을 받는다."

올바른 이해:

"공통 칸(session_id, cwd 등)은 같지만,
 이벤트마다 고유 칸이 다르다.
 PreToolUse엔 tool_name, UserPromptSubmit엔 prompt."

미니 시나리오: 어떤 파일이 수정될 때마다 그 파일 경로를 기록하고 싶다. → PreToolUse에서 tool_input.file_path를 읽어 남기면 돼요.

직접 따라 하기 (실습)

작은 훅을 하나 만들어 봐요. 목표: Edit 또는 Write로 파일을 고친 직후 자동으로 린트를 돌리고, 30초 안에 못 끝나면 멈추기.

.claude/settings.json에 이렇게 적어요.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

한 줄씩 읽으면: - PostToolUse → 도구가 성공으로 끝난 직후에 실행 - matcher: "Edit|Write" → Edit 또는 Write일 때만 반응 - type: "command" → 명령 종류 (지금은 이것만 있음) - command: "npm run lint" → 실행할 명령 - timeout: 30 → 30초 넘으면 취소

이제 클로드 코드가 파일을 고칠 때마다 린트가 자동으로 돌아요.

연습문제

문제 1 (기본)

훅(Hook)이 무엇인지 한 문장으로 설명하고, 훅을 쓰면 좋은 점 두 가지를 적어보세요.

문제 2 (기본)

훅 설정 파일 3곳의 위치와 적용 범위를 적어보세요. 팀 공통 훅과 개인 훅은 각각 어디에 적어야 할까요?

문제 3 (중급)

matcher는 어떤 두 이벤트에서만 쓰나요? 그 이유를 함께 적어보세요.

문제 4 (중급)

다음 요구사항을 만족하는 훅 JSON을 적어보세요. (1) Edit 또는 Write로 파일을 고친 직후 자동으로 npm run lint를 실행 (2) 타임아웃은 30초

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

문제 5 (심화)

PreToolUse와 PostToolUse가 받는 정보(JSON)의 공통점과 차이점을 적어보세요. PostToolUse에만 있는 칸은 무엇이고, 왜 그럴까요?

이 장 한 장 정리

• 훅(Hook): 정해진 순간에 내 명령을 자동 실행하는 장치.
• 설정 파일 3곳: ~/.claude/settings.json(전체) / .claude/settings.json(프로젝트) / .claude/settings.local.json(나만).
• JSON 구조: 이벤트 → matcher → hooks → command 순으로 한 겹씩.
• 7가지 이벤트: PreToolUse, PostToolUse, Notification, UserPromptSubmit, Stop, SubagentStop, PreCompact.
• stdin 정보: 공통 칸(session_id, cwd 등) + 이벤트별 고유 칸. PostToolUse에만 tool_response.

안내: 훅 이벤트 이름·설정 방식은 시간이 지나면 바뀔 수 있어요. 실제 적용 전 클로드 코드 공식 문서에서 최신 내용을 확인하세요.

다음 장 예고

다음 장에서는 또 다른 주제를 다뤄요. 지금 몰라도 됩니다.